<html>

<head>
<title>R documentation</title>
</head>

<body>
<h1>R documentation</h1>

<h2>Data types</h2>

<p> For R, ParameterWeaver supports the following data types:
<ol>
  <li> <tt>integer</tt> </li>
  <li> <tt>double</tt> </li>
  <li> <tt>logical</tt> </li>
  <li> <tt>string</tt> </li>
</ol>
</p>

<h2>Example R script</h2>
<p> Suppose we want to pass command line parameters to the following R script:
<pre>
if (nchar(out) &gt; 0) {
    conn <- file(out, 'w')
} else {
    conn = stdout()
}
if (verbose) {
    write(sprintf("# n = %d\n", n), conn)
    write(sprintf("# alpha = %.16f\n", alpha), conn)
    write(sprintf("# out = '%s'\n", out), conn)
    write(sprintf("# verbose = %s\n", verbose), conn)
}
for (i in 1:n) {
    write(sprintf("%d\t%f\n", i, i*alpha), conn)
}
if (conn != stdout()) {
    close(conn)
}
</pre>
We would like to set the number of iterations <tt>n</tt>, the factor <tt>alpha</tt>, the name of the file to write the output to <tt>out</tt> and the verbosity <tt>verbose</tt> at runtime, i.e., without modifying the source code of this script. </p>
<p> Moreover, the code to print the values of the variables is error prone, if we later add or remove a parameter, this part of the code has to be updated as well. </p>
<p> Defining the command line parameters in a parameter definition file to automatlically generate the necessary code simplifies matters considerably. </p>

<h2>Example parameter definition file</h2>
The following file defines four command line parameters named <tt>n</tt>, <tt>alpha</tt>,  <tt>out</tt> and <tt>verbose</tt>.  They are to be interpreted as <tt>integer</tt>, <tt>double</tt>, string and <tt>logical</tt> respectively, and if no values are passed via the command line, they will have the default values <tt>10</tt>, <tt>0.19</tt>, <tt>output.txt</tt> and false respectively.  Note that a string default value is quoted, just as it would be in R code.  In this case, the columns in the file are separated by tab characters.  The following is the contents of the parameter definition file <tt>param_defs.txt</tt>:
<pre>
integer	n	10
double	alpha	0.19
string	out	'output.txt'
logical	verbose	F
</pre>
This parameter definition file can be created in a text editor such as the one used to write R scripts, or from a Microsoft Excel worksheet by saving the latter as a CSV file. </p>
<p> As mentioned above, logical values are also supported, however, the semantics is slightly different from other data types.  The default value of a logical variable is always false, regardless of what is specified in the parameter definition file.  As opposed to parameters of other types, a logical parameter acts like a flag, i.e., it is a command line options that doesn't take a value.  Its absence is interpreted as false, its presence as true. </p>

<h2>Generating code</h2>
<p> Generating the code fragments is now very easy.  If appropriate, load the module (VIC3):
<pre>
$ module load parameterweaver
</pre>
Next, we generate the code based on the parameter definition file:
<pre>
$ weave -l R -d param_defs.txt
</pre>
<p> Three code fragments are generated, all grouped in a single R file <tt>cl_params.r</tt>.
<ol>
  <li> Initialization: the default values of the command line parameters are assigned to global variables with the names as specified in the parameter definition file. </li>
  <li> Parsing: the options passed to the program via the command line are assigned to the appropriate variables.  Moreover, an array containing the remaining command line arguments is creaed as <tt>cl_params</tt>. </li>
  <li> Dumper: a function is defined that takes two arguments: a file connector and a prefix.  This function writes the values of the command line parameters to the file connector, each on a separate line, preceeded by the specified prefix. </li>
</ol>
</p>

<h2>Using the code fragments</h2>
<p> The code fragments can be included into the R script by sourcing it:
<pre>
  source("cl_parser.r")
</pre>
The parameter initialization and parsing are executed at this point, the dumper can be called whenever the user likes, e.g.,
<pre>
  dump_cl(stdout(), "")
</pre>
The code for the script is thus modified as follows:
<pre>
source('cl_params.r')
if (nchar(out) &gt; 0) {
    conn <- file(out, 'w')
} else {
    conn = stdout()
}
if (verbose) {
    dump_cl(conn, "# ")
}
for (i in 1:n) {
    cat(paste(i, "\t", i*alpha), file = conn, sep = "\n")
}
if (conn != stdout()) {
    close(conn)
}
</pre>
Note that in this example, additional command line parameters are simply ignored.  As mentioned before, they are available in the vector <tt>cl_params</tt> if needed. </p>

</body>

</html>
